/*   The MIT License
 *   
 *   Carina Common
 *   Copyright (c) 2010-2011 Zdravko Velinov
 *   
 *   Permission is hereby granted, free of charge, to any person obtaining a copy
 *   of this software and associated documentation files (the "Software"), to deal
 *   in the Software without restriction, including without limitation the rights
 *   to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 *   copies of the Software, and to permit persons to whom the Software is
 *   furnished to do so, subject to the following conditions:
 *
 *   The above copyright notice and this permission notice shall be included in
 *   all copies or substantial portions of the Software.
 *
 *   THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 *   IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 *   FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 *   AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 *   LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 *   OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 *   THE SOFTWARE.
 */

#ifndef EXCEPTION_HH_
#define EXCEPTION_HH_

#include "carina/common/global.hh"

#include <exception>

namespace Carina
{
/*! \brief Exception type used for crashing gracefully the application.
 * 
 *  Of course, it could be handled elsewhere to prevent crashes. For example, that
 *  could be useful for development tools. Joke apart; you shouldn't use exceptions
 *  for error handling because it is inefficient. Also, in some cases you might want
 *  to use asserts because they have a nicer dialog that enables suppressing errors.
 */
class Exception: public std::exception
{
    string _what; //!< The reason why the application crashed.
public:
    /*! \brief Constructor.
     * 
     *  \param what_happened what is the reason why this condition has occurred.
     */
    Exception(const string& what_happened) throw()
        :   _what(what_happened) {}
        
    //! Destructor.
    virtual ~Exception() throw() {}

    //! Return the reason why the application crashed.
    virtual const char* what() const throw() { return _what.c_str(); }
};


/*! \brief The preferred way to throw an exception.
 * 
 *  The difference between just directly throwing the exception is that there
 *  is additional information prepended to make it easier for debugging, i.e.
 *  file name and line.
 */
#define THROW_EXCEPTION(s) \
    throw Carina::Exception(__FILE__ ":" TO_STRING(__LINE__) ": " + (string)s)

//! Re-throwing exceptions with additional information.
#define THROW_EXTENDED_EXCEPTION(e, s) throw Carina::Exception(e.what() + string(s))
}

#endif /* EXCEPTION_HH_ */
